//+------------------------------------------------------------------+
//|                                      DefaultEqualityComparer.mqh |
//|                             Copyright 2000-2025, MetaQuotes Ltd. |
//|                                             https://www.mql5.com |
//+------------------------------------------------------------------+
#include <Generic/Interfaces/IEqualityComparer.h>  // 相等性比较器接口（定义“相等判断”与“哈希计算”双能力）
#include "EqualFunction.h"                         // 基础相等性判断函数库（提供各类型默认相等逻辑）
#include "HashFunction.h"                          // 基础哈希函数库（提供各类型默认哈希值计算逻辑）

//+------------------------------------------------------------------+
//| CDefaultEqualityComparer<T> 类：默认相等性比较器实现类             |
//| 核心定位：实现 IEqualityComparer<T> 接口，作为所有支持相等性判断与哈希计算的类型（基础类型/自定义类型）的默认比较器， |
//|           无需用户手动实现核心逻辑，直接复用底层工具函数的能力，支撑哈希表、集合等依赖“相等性+哈希”的组件 |
//| 核心特性：                                                      |
//|  1. 双接口实现：同时实现“相等性判断（Equals）”与“哈希计算（HashCode）”，完全满足 IEqualityComparer<T> 接口要求； |
//|  2. 类型全兼容：自动适配所有支持 `::Equals` 和 `::GetHashCode` 函数的类型（包括 MQL5 基础类型与实现对应逻辑的自定义类型）； |
//|  3. 零配置使用：无需用户编写任何适配代码，直接实例化即可接入依赖相等性比较器的组件（如 HashSet/HashMap）； |
//|  4. 逻辑一致性：相等性判断与哈希计算严格匹配（若 x.Equals(y) 为 true，则 x.HashCode() == y.HashCode()），避免哈希表逻辑错误； |
//| 适用场景：所有**无需自定义相等性规则与哈希算法**的场景，即使用“自然相等逻辑”与“默认哈希算法”，典型如： |
//|  - 哈希集合去重（如用 HashSet<int> 存储唯一 ID，依赖默认相等判断与哈希计算实现高效去重）； |
//|  - 哈希映射存储（如用 HashMap<string, Order> 存储订单，通过字符串键的默认哈希与相等判断实现快速查找）； |
//|  - 基础类型相等性校验（如判断两个 datetime 是否为同一时刻、两个 double 是否数值相等，复用默认逻辑）； |
//|  - 自定义类型标准化适配（自定义类型已实现 `::Equals` 和 `::GetHashCode` 全局函数，直接通过默认比较器接入哈希组件）； |
//+------------------------------------------------------------------+
template<typename T>
class CDefaultEqualityComparer : public IEqualityComparer<T>
  {
public:
   /**
    * @brief 默认构造函数：创建默认相等性比较器实例
    * @note 无状态设计，实例化后即可直接使用，无需额外初始化（如配置比较规则、哈希参数等）
    */
                     CDefaultEqualityComparer(void);

   /**
    * @brief 析构函数：清理默认相等性比较器资源
    * @note 无动态内存分配（不持有外部对象引用），仅执行基础析构逻辑
    */
                    ~CDefaultEqualityComparer(void);

   /**
    * @brief 相等性判断：判断两个对象是否相等（实现 IEqualityComparer<T> 接口的核心方法）
    * @param x [in] 待比较的第一个对象（类型与泛型参数 T 一致）
    * @param y [in] 待比较的第二个对象（类型与泛型参数 T 一致）
    * @return bool - 相等性结果：
    *               - true：两个对象相等（按对应类型的默认相等规则）；
    *               - false：两个对象不相等（按对应类型的默认相等规则）；
    * @note 核心逻辑：直接调用全局相等性判断函数 `::Equals(x, y)`（定义于 EqualFunction.mqh），具体规则由该函数决定：
    *       1. 若 T 为基础类型（如 int/bool/string/datetime）：使用类型原生相等逻辑（如 int 按数值、string 按字符序列、datetime 按时间戳）；
    *       2. 若 T 为自定义类型：调用为该类型实现的全局 `::Equals` 函数（需用户提前实现，否则可能返回默认值导致判断错误）；
    *       3. 特殊处理：对浮点型（float/double）会考虑精度误差（具体逻辑由 EqualFunction.mqh 定义），避免因精度问题误判不相等；
    */
   bool              Equals(T x, T y);

   /**
    * @brief 哈希计算：为指定对象生成哈希值（实现 IEqualityComparer<T> 接口的核心方法，与 Equals 逻辑强关联）
    * @param value [in] 待计算哈希值的对象（类型与泛型参数 T 一致）
    * @return int - 哈希值（32位整数，用于哈希表的桶索引计算）
    * @note 核心逻辑：直接调用全局哈希函数 `::GetHashCode(value)`（定义于 HashFunction.mqh），确保与 Equals 逻辑匹配：
    *       1. 一致性保证：若 `Equals(x, y) == true`，则 `HashCode(x) == HashCode(y)`（避免哈希表中“相等对象存入不同桶”的逻辑错误）；
    *       2. 类型适配：
    *          - 基础类型：使用针对该类型优化的哈希算法（如 string 按字符序列哈希、int 直接返回自身值、datetime 按时间戳哈希）；
    *          - 自定义类型：调用为该类型实现的全局 `::GetHashCode` 函数（需用户提前实现，确保哈希值与相等性逻辑匹配）；
    *       3. 哈希分布：默认算法尽量保证哈希值均匀分布，减少哈希表的碰撞概率，提升查找效率；
    */
   int               HashCode(T value);
  };
//+------------------------------------------------------------------+